fix(db): align join keys with equality identity - #1834

Align live-query join keys with the query engine's existing equality identity. Joins now agree with eq for binary, Date, Temporal, scalar, BigInt/non-finite, and opaque-reference values; nullish operands are unmatched across direct, correlated, eager, and lazy joins.

Root cause

The lazy-demand optimizer reused an already-normalized join key as the backend query operand. For binary values, the collection index then normalized that internal string as a user string, so double normalization prevented the candidate from matching. The graph needs the equality identity as its key while lazy demand retains the raw operand. Separately, full and correlated joins allowed nullish operands from opposite sides to share a bucket.

Approach

• Key non-nullish join operands through the existing graph-local ValueIdentity exactly once.
• Give nullish operands compact side-local keys so opposite sides cannot match while same-side rows share one efficient bucket.
• Retain the raw operand beside the graph key for lazy subset demand, with one stable representative and deterministic reference weights per equality class.
• Remove the compiler's redundant post-join filter; db-ivm already guarantees the selected inner/left/right/full result shape, so the result mapper can be a direct pipe operator.
• Keep the repair inside the query compiler; db-ivm, public APIs, exports, dependencies, and compatibility branches are unchanged.

Key invariants

• A direct join, eq, and a filtered cross join agree over every established equality domain.
• Equal binary copies match; unequal bytes and normalization-like strings remain disjoint.
• null and undefined never match in joins, including when row keys overlap across sides.
• Lazy demand receives original values, retires keys deterministically, and does no duplicate candidate work.
• Route/correlation identity remains part of routed join keys.
• The four supported join modes preserve the output shapes owned by db-ivm without a duplicate compiler filter node.

Non-goals

• Compound and(eq(...), eq(...)) join conditions from Allow joins with an and() condition #593/feat: support compound join conditions with and() (issue #593) #861 remain design-gated. The public join contract accepts one equality condition; this PR adds no join language or composite-key syntax.
• This does not revive global index normalization, string-prefixed binary keys, the reference-equality policy from Remove Uint8Array content-based equality comparison #1258, or other additive portions of old proposals.

Trade-offs and package weight

Failing fast for established Date/Temporal/binary/reference equality would narrow existing query behavior, so the repair reuses the current identity relation instead. The emitted machinery is limited to a private getJoinKey helper and one function-scoped demand-weight map; the map keeps one raw representative per live equality class while balancing inserts and retractions. JoinInputValue is type-only.

The review pass replaced per-row nullish serialization with two inline side sentinels, removed an unused helper argument, and deleted a redundant post-join filter/closure. Recomputing the raw operand instead of retaining the tuple's third slot was rejected because it repeats expression evaluation and increased minified gzip by another 43 B ESM / 21 B CJS in the measured variant. Folding key policy into call sites and sharing unrelated demand bookkeeping were rejected because they reduce locality or broaden the change after the zero-growth target is met. Production TypeScript is net +1 line.

Against exact base 3ad64a42a0088e1272176fb33c953526fed9b868, every requested shipped-size measurement is now negative (85 modules per format, deterministic /usr/bin/gzip -n -9, Brotli q11/text):

The complete normal/minified dist trees shrink by 1,392 B / 766 B. The 641-entry npm package shrinks by 124 B packed / 1,616 B unpacked after a normal build and 78 B packed / 990 B unpacked after a minified build. There are no new exported state fields, public APIs, exports, dependencies, compatibility branches, package metadata changes, or db-ivm production changes.

Verification

• Exact base 3ad64a42a0088e1272176fb33c953526fed9b868: the 30-cell focused owner selection is RED (16 failed, 14 path/control passes) across binary, Temporal, nullish, lifecycle, and raw lazy-demand paths.
• This branch: the same 30-cell selection is GREEN (30 passed), with positive execution in both autoIndex: off and eager modes.
• The historical combined implementation path is killed by the RED baseline. A missing-nullish-side mutant is independently killed (4 failed), and an illegal upstream inner-join shape mutant is killed by five direct db-ivm owner tests.
• Full join owner: 126/126 passed.
• Final cold-reconciliation/subquery/scheduler collateral: 119/119; direct db-ivm join owners: 60/60. Earlier equality/lifecycle collateral passed 229/229; hash/value controls passed 90/90; join/index boundary passed 71/71.
• Full DB runtime gate with two workers and type-only files excluded: 178 files / 5,930 tests passed.
• Focused join type specs: 36/36 passed; the standalone invocation separately reports the repository's known 35 cross-package rootDir diagnostics. Normal and minified @tanstack/db builds, including declaration generation, passed.
• Changed-file ESLint, Prettier, git diff --check, and the commit hook passed.

Key rerun commands:

../../node_modules/.bin/vitest run tests/query/join.test.ts --maxWorkers=1 --minWorkers=1
../../node_modules/.bin/vitest run tests/query/join-subquery.test.ts tests/query/cold-join-reconciliation-oracle.test.ts tests/query/scheduler.test.ts --maxWorkers=1 --minWorkers=1
../../node_modules/.bin/vitest run --typecheck.enabled=false --maxWorkers=2 --minWorkers=1
../../node_modules/.bin/vite build
../../node_modules/.bin/vite build --minify

Files changed

• packages/db/src/query/compiler/joins.ts: unify join keying with ValueIdentity, preserve raw lazy-demand values, and remove redundant result filtering.
• packages/db/tests/query/join.test.ts: permanent cross-formulation, lifecycle, disjointness, nullish, and lazy-work coverage.
• .changeset/fix-query-join-equality.md: patch release note for @tanstack/db.

Provenance and credit

Addresses the binary join inconsistency reported in #896 and credits/supersedes the approach in #899. No closure keywords are used because #896 is already closed, the other referenced records are pull requests or partial/design-gated work, and no material prior implementation code was copied (so no co-author trailers are warranted).